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1. INTRODUCTION 

PROGRAMING - The art of creating logical computer programs. 

PROGRAMER - A person who prepares problem solving procedures 
through functionally designed and logically coded 
routines for the computer to execute and wno 
typically also debugs those routines. 

The purpose of this document is to provide engineers, 
programmers and managers with software development procedures 
which may be applied in the development of computer software 
systems. The intent of the procedures presented is to 
promote quality and uniformity of FORTRAN programs ana 
thereny lessen the time and cost of program development, 
maintenance, and modification, and to increase program 
efficiency and reliability. 

The key to program reliability is to design, develop, and 
manage software with a formalized methodology whxcn can be 
used by computer scientists and applications engineers to 
describe concepts, perform data analysis, and evaluate 
systems with visual, conversational, and descriptive aata 
prints or data displays. 

The first step in defining and developing a system (ne it a 
large software program or just a few small routines) with a 
formal methodology is to apply a formalized set of rules and 
enforce those rules, especially on a large project wmcn is 
subject to change of personnel or task definition. This 
document presents a set of rules which may be applied oy a 
FORTRAN programmer/engineer to aid him in writing efficient, 
reliable, easy to change, and system compatible programs. 
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PAGE t$ 

QUALITY 

DESIGN CONSIDERATIONS 

2. 1 /. NAIYSlg 

The first step in solving a scientific problem is to analyze 
the problem. Then a functional design to solve the promem 
can ne made. Of primary importance are the logical rlow or 
the program, data tables, equations and definition or 
variables to be programmed, wnere and now the program is to 
be executed, the program's input/output, and other special 
considerations and/or constraints. 

The logical flow should be a simple sequence or descriptive 
block steps, including equations, with side comments 
concerning future program expansions and possible 
constraints. These descriptive blocks should verbalxy 
describe the functions to be perrormed and should never 
include programming language. 

2.2 NODUL ABIZA l'ION 

After the problem has been analyzed and a functional design 
developed, the next important step before coding tne program 
is to derine all the possible routines or modules. Each 
module should be a function of tne level of execution 
required. This will reduce program complexity, improve 
program clarity, and permit easier modifications ana program 
checkout, easier production program maintenance and easier 
building of a new advanced product. 

The following are guidelines that the coaer should roxlow: 

1. Each module should be well documented internaxxy xy 
the use of header and in-line comments. 

2. Use as many levels of modularxty as needeu to 
simplify program control flow. 

3. Organize modules logically to make the program 
easier to understand and modify . 

4. Allow room for expansion without destroying 
simplicity of sequential flow. 

5. Each module's variaolas and arrays snculd ue wexi 
defined and the source of each given. 

b. Use separate module for data input/output. 

7. Use separate module for each specialized function; 
I.E. nit manipulation function or frequently called 
mathematical function. 
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8. nodules should not be larger than 100 lines of 
executable code. 

2.3 £l&W£ill&m£ 

The functional logic flov of the program say be in the 
fora of a structured flow using structured logic 
symbols, or a functional level program design language, 
PDL. 

2.3.1 SYMBOL IC 

in general, a rlovchart gives a pictorial 
representation of logic within the program ana 
its routines. The flowchart should be reaaily 
understandable to the extents that other 
programaers/engineers could code the routines 
without lengthy deciphering. 

The following are the suggested conventions: 

• Use flowchart symbols wmch have been aefmed 
as standard for the project (s) problem, for 
structured flowchart symbols refer to 
figure 1 

• Use page number references to indicate logical 
connections 

• Include all subroutine and executive 
references 

• Use programming language for equations ana 
logic 

• Use structured program flov; that is, tne main 
program or module flow is always top/dovn on 
the left side of the paper and the 
intermediate flov is from left to ngnt ana 
top/down 

2.3.2 PROGRAM DE SIGN L ANGUAGE 

The program design language PDL is a tool ror 
desig mg programs in detail prior to coding. 

Its t *rpose is to enable one to express the logic 
of a program in an English-like language. 

Figure 2 illustrates the PDL usage. 
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PROCESSING 

A group o f instructions whicn perxorm 
a processing function or the routine. 



EXTERNAL PROCESSING 
Identifies the exit to and return 
from an external function or 
subroutine with its calling arguments 
which performs a processing function 
of the routine. 




DEC IS I ON /DO 

,The decision function used to 
document points in the routine where 
a branch to alternate patns is 
possible based upon variable 
conditions or the DO loop 
specification statement. 


TERMINAL INTERRUPT 

The beginning, end, or point or 

interruption in a routine. 



OFF PAGE r'LOk TRANSFER 
A connector usea to show that iio« 
transfers to another part ox tnc x*ow 
chart. The symbols i ana n indicate 
a transfer to entry numner 1 on pa^e 
number n of the flow chart. 



ENTRY INDICATOR 

An indicator that shows an entry into 
the logic flow from another part ox 
the flow. The entries on each page 
are seguentially numbered 1, 2, ... 


Figure 1. - Structured flowchart symbols 





The basic unit of a structured flow 
chart is the segsent. A segment is a 
aodule that has a single entrance and 
a single exit. This segsent 
accoaplishea the procesring 
identified within. 



The If THEN ELSE 
sycbol with the 
else clause. 




A segaent that is an external 
reference to another routine. 


The terninal interrupt - the 
beginning, end, or poiat of 
interruption in a program. 


figure 1. - Continued 



Symbol 


** "X* quality 


Osage 



1 

DO whiles. 

f 

CP) / 

1 

1 

do wm\ 

/ 

(P) / 

I 

_l 

DO FOR. \ 

/ 

■l 3 m h m. ijnJ 




The IF Thhh ELSE 
symbol with a null 
else clause. 


The DO BrilLE symnol. 


The DO UNTIL symbol 


The DO FOB symbol. 


Figure 1. - Concluded 
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The PDL has the following advantages: 

• It states logic in an easy-to-read fashion 

• It permits concentration on logic; it frees 
the designer/prograaner with the low-level 
details of coding 

• It can be converted easily to executable code; 
this is accoaplished by step-vise refining the 
English-like stateaents until they oecome 
stateaents of a higher level language 

« It contributes to the readanility aspect of a 
structured walkthrough for the non prog raaaers 

• It can be used to teach structured 
programming; in fact it is a aethod of 
expressing structured programing logic 

• It can be retained as convents at tne 
beginning of a program for documentation 
purposes 

• It can be kept on the file in the text mode, 
updated using the editor, and listed 

The main disadvantage to the PDL usage is: 

• It does not present . the logical flow 01 the 
problem in a pictorial form 

2.4 EXISTING PR OGRAMS AMD SUBRO UTINES 

Before writing a program, search for available pio^rams 
and s ubroutines related to your problem. These may do 
all or part of the job, or may be useful in analysis. 

When designing a system, a file should be startea which 
contains all program, subroutine and function names, as 
well as any entry points within routines. This wiio. 
avoid future use of a routine name which is axreaay in 
existence. 
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INITIATE PROGRAM 
GET FIRST TEXT RECORD 
DO HHILE MORE TEXT RECORDS 
DO HHILE MORE NOR DS 

GET NEXT TEXT HORD 
SEARCH TABLE FOR HORD 
IF HORD FOUND 

TdEN INCREMENT HORD<S COUNT 
ELSE HORD NOT IN TABLE 

INSERT HORD INTO ThE TABLE 
END IF 

INCREMENT HORD PROCESSED COUNT 
END DO END OF TEXT RECORD 
GET NEXT TEXT RECORD 
END DO ALL RECORDS HAVE BEEN PROCESSED 
PRINT TABLE 
TERMINATE PROGRAM 


Figure 2 


A PDL example 
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2.5 C OMPATIBILI TY 


2.5.1 LOGICAL UNIT 


When designing a system, logical unit assignments 
within programs snould re planned and be 
designated before any programming starts. Tms 
way any inconsistencies' in future file usage can 
be eliminated beforehand, and cumbersome and 
time-consuming releases between executions can be 
avoided. 


2.5.2 USE OF F LA GS 

Be consistent in the use of flags on input earns 
to avoid confusing production personnel setting 
up the prograa decks. For example, a zero or 
blank value could always iapiy "do not do", and a 
nonzero values can describe more than one "do" 
condition (e.g., 0 = do not plot, 1 = plot on 
linear grid, 2 - plot on log grid; or u = ao not 
calibrate data, 1 = calibrate using poly nominal 
expansion, 2 = calibrate using linear 
interpolation) . 


2.5.3 C0MS1STANC Y AMONG VA RIABLES 

Extend tnis same consistency to all otner 
variables used in different programs suen as 
start times, stop times and time biases, it is 
nerve-racking to production personnel, to say the 
least, to have one program read a start time in 
integer days, hours, minutes and seconds; a 
second program read it in interger milii- seconds; 
and a third program read it in floating-point 
seconds. The field size for these variables 
should also be identical in ail programs. 


When using additive aid multiplicative time 
biases to correct or convert time in a program, 
their usage should ut specified beforenana to 
avoid future problems. Sometimes one program 
will add the additive bias and another one vui 
subtract it; sometimes a program will add first 
and then multiply, and a second program will 
multiply first and then add. Obviously, these 
operations will not give tne same results. 
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2.5.4 &Cjil£3-£££gj!D££l Mliil 

Keep the machine - dependent portions of a program 
separate : for example, plan individual nodules 
for I/O operations. This simplifies conversion 
to otner computing systems. 

2.5.5 USE OF SPECI AL C OMPILER FEATURES 

Do not use special features provided by a 
particular compiler unless it is absolutely 
necessary. When special features are used# tney 
should# of course, be identified and justified m 
comments. 

2.6 INPUT AND OUTPUT DATA 

2.6.1 GENERAL 

Design a program so that input data are easy to 
create and output data easy to read. 

2.6.2 GROUPIN G BY CASE S 

When data can be distinctly grouped for separate 
cases# provide a means of fi using data for the 
current case and going on to the next. This way# 
an irrecoverable error in processing one case 
does not necessarily preclude processing others. 

2.6.3 INTE RME DI ATE OUTPUT 

Make available to the. user an option for 
ontaining selected intermediate output. An input 
code can easily be used to indicate which 
intermediate results# if any, are desired. 
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2.7 ADA PTABILITY CHECKOUT 

2.7.1 CHECKOUT METHOD 

Plan your checkout method while designing a 
program . Organize the program so checkout data 
are easy to prepare. Hake up a block diagram and 
preiiainary checkout data before coding. Use tne 
checkout data and block diagran in "desk 
checking" the program. 

2.7.2 USAG E OF WHITE STATEMEN TS 

Organize the program so that WHITE statements, 
causing meaningful printouts at several points in 
the program, can be inserted for checkout. Tnese 
are explained in detail in section 4.1. 

2.8 G ENE RAL- PUR POSE SUB R OUTINES 

Tne primary influence on the design of a general-purpose 
subroutine (i.e., a subroutine reasonably expected to ne 
used in two or more unrelated programs) should be 
correct results within the required r ange of accuracy . 

Mini mizat ion of s torage and execution time should be 
considered next. 
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COOING 

3.1 CO MMEN TS 

3.1.1 GEN ERAL 

Make your program self-explanatory by including 
meaningful comments throughout. Since most 
programs outlive their autnors 1 responsibility 
for them, and because no computer is permanent , 
your program will probably be modified according 
to new machine software, or performance 
requirements. If these comments are properly 
prepared, they will provide sufficient 
documentation for most routines and aide in 
conversion and modifications. 

The comments needed to document a subroutine fail 
into tne following classes: 

• Routine header comments at tne top or the 
routine 

• Comments at various places in the code to 
describe tne logic flow in the routine. 
Depending on the complexity of the program, 
the number of necessary comments varies, but 
usually the ratio of comments to statements 
should be at least 1:5 

• Special comment? in large routines to 
segment the code into logical blocks 

The general structure of the program or 
subprogram is given in figure 3. 

3.1.2 HEADER COM MENTS 

Identify the program or subprogram in a comment, 
at the beginning of the listing. Comments snould 
follow this card to provide a program abstract 
answering such questions as: What does the 

program do? it is confined to any particular 
application? Is it a special version? Why was 
it written, by whom, and when? It is derived 
from or directly related to another program? Are 
any relevant references punnsned? See rigure 4 
for tne structure of these comments. 



on n n r. o n o no 
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R0UI1MS OUikUl Zkl* ^ 


C********* ******************************************************* 


header comments 


c 

£** ******** ********* ********* **************** ******************** 


non- executable statements 


executable statements 

CALI. EXIT OR RETURN 


format statements 


END 


Figure 3 


Routine general structure 


ORIGINAL PAGEJ® 
OF POOR QUALITY 


m 

£**+**4 ******* ****** ****** HEADER COMMENTS************************ 


C 

C 

C 

C 

C 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 


c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 


PROGRAM NAME ( or SUBPROGRAM NAME) 

The name of the program (or subprogram) should be here 
LAST UPDATE: date of the last major revision 


AUTHOR 

Author's name 
co. Division 
Company name 
Date originated 

PURPOSE 


NASA MONITOR 

Tecnnicai Monitor's name 

NASA Division 

NASA JOHNSON SPACE CENTER 


The purpose of the program should be defined nere in 
several sentences. 


INPUT VARIABLES 

This section defines tne variables INPUT to the sub- 
program whose value the subprogram does not cnange. 

This includes all variables passed by the calling 
routine to the subprogram through both calling arguments 
and COMMON blocks. A sample format follows: 

VARIABLE COMMON BLK DESCRIPTION 


VARBL1 

BLOCK 1 

DETERMINES HOK MANY TIMES - 

XPOS 

NONE 

POSITION OF IhL 1 VECTOR 

OUTPUT VARIABLES 



Inis section defines the variables OUTPUT by tne sub- 
routine to whose value the subroutine DOES NCI USE cut 
DOES CHANGE. This includes variables returned to the 
calling routine both in the calling arguments and in 
COMMON blocks. The rormat should be similar to tnat 
of the INPUT VARIABLES section. 


Figure 4 


header comments 
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C INPUX/OUTPUT VARIABLES 
C 

C This section defines those variables wmch are usea roc 

C BOTH INPUT AND OUTPUT, i.e., a variable whose vaxue is 

C INPUT to the subprogram AND vhose vaxue the subprogram 

C CHANGES. The format should be similar to the xNPUl 

C VARIABLES section, 

c 

C PROGRAM VARIABLES 

C 

C This section defines the primary variables tnat are 

C neither input nor output variables, lhe format snouia 

C be similar to that of the INPUT VARIABLES section, except 

C that a "COMMON BLK" column is not needed. Ail internal 

C "flag" should be defined here, and vnat each of tue 

C various codes mean. 

C 

C SUBPROGRAMS REQUIRED 

C 

C This section briefly defines ail subprograms wmcn tne 

C subject routine requires. A one or two sentence sno uid 

C ne used to state the basic function (purpose) oi each 

C subprogram. A sample format follows; 

C 

C tiATMUL - SUBROUTINE THAI PERI OEMs MATRIX MULllPLlCaT xoN 

C 

C ASSIGN - GENERAL PURPOSE SUBROUTINE Which ISSUES A 

C COMMAND TO THE OPERATING SYSTEM TO hnSG A 

C SPECIFIC FILE 

C 

C REMARKS 

C 

C Any special considerations, requirements, restrictions, 

C etc., should be mentioned here 

C 

c** ***************** ******H£ADER comments************************ 


Figure 4 


Conduced 
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3.1.3 £RQ££M miUChUQiS. 

Program modification should be noted by tne date 
and number of modification (1, 2, 3 , . .) ana tne 
name of the programmer making it. 

3.1.4 SUBR OUTINE COMMENTS 

For a subroutine/ comments describing the calling 
sequence should follow the identification 
information, identify eacn argument as input, 
input/output/ or output; and explain its purpose, 
type, dimension, etc. The different values that 
an indicator (such as an error code) can assume 
should be defined, for botn input and output. 
Also, all variables used in common blocks snould 
be similarly identified. 

3.1.5 DISTRIBUT ION OF COMMENTS 

Distribute comments describing and summarizing 
the computation appropriately throughout the 
listing. These should correspond in terminology 
to the program block diagram. Clever, nut 
possibly obscure, coding should be explained in 
detail; for example, if the function J=2*i-i/3-1 
is used in a loop, where I takes on the values 1 
through 6, the following might be written: 

C AS I = 1,2, 3, 4, 5, 6 J = 1,3,4,6,3,S 

3.1.6 ERROR RECOVE RY 

Explain error recovery procedures in comments. 
This information is important to those who 
maintain or modify the program. 

3.1.7 ARRAY DIMENSIONS 

Explan m comments any reasons for peculiar array 
dimensions; e.g. , storage limitations or use my 
other routines. 

3.1.8 PRINTIN G STYLE 

Use a conspicuous printing styre for comments so 
that they stand out from tne rest of the listing. 
Separate comments from statements by cards that 
are blank except for the C in column 1 (aitnougn 
the listing looks cleaner without the C, some 
compilers object to totally blank cards) . 

Comments are futher accented if they are 
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indented, starting in, say, colum 15. Short but 
important consents can be empnasized by inserting 
a blank between each letter of each word, and 
four blanks between words; tor example, 

C INPUT EDITING SECTION 

Similarly, symbols that are separated from words 
by two blanks instead of one stand out better in 
phrases. For example, 

C WITH RADIUS h AND HITH H, K FUR CENTER 

khen spacing comments and statements, consider 
inclusion of the program listing in the program's 
formal document. 

3.1.9 PROGRAM MODULARIZA TION CCMME jllS 

For program modularization, comments snowing the 
program structure and flow on a higher level are 
used to divide the program into segments. These 
comments provide the mechanism to show the 
structure of the logic. 

3.2 INITIALI ZATI ON 

Do not expect main storage to be initialized at tne 
beginning of the execution. 

Do not assume that a tape is properly positioned. 

Rewind it before use and, unless it is a scratch tape, 
unload it afterward. 


3.3 STATEMENT ORDERING AND NUMB ERI NG 
3.3.1 NON“ I £££££ AB LE 

Place specification statements (e.g., DIMENSION, 
COMMON) at the beginning or the program. Tne 
symbol lists within type, DIMENSION, ana COMMON* 
are to be alphabetical. However variables which 
functionally go together may be yroupea, even 
thougn they may not be alphabetical, me symbol 
lists are to be colummzed ana left justified. 
This way they are easy to find and do not 
interrupt following of the logic flow. Further, 
some compilers object if these statements are not 
placed first. See figure 5. 


o n o o o n o no 
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Program declaration statements 


SEAL MACE, 

INT2GEB X , Y 

other type statements and IMPLICIT statements 


DIMENSION AS (100), A»AME (50), — 

1 , VNAM£l( 30), X (25), — 

2 
3 


COMMON/COfi 1 

1 

2 

COMMON /C0M2 

1 

2 


/ X ( 10) , AEcEAY ( 50) , 
, AERAY1 (300) , 

/ - 


9 


EQUIVALENCE (AAA ( 1), BBB (10)), (XXXXXX(20) , YY (50) ) 
1 , f CCCCCC (20) , DDDDDD ( 1)), 


DATA 

1 

2 


Figure 5. - Speciiication statements 
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The order of the specification statements snoula 
jje in the following order: 

TYPE 

DIMENSION 

COMMON 

EQUIVALENCE 

DATA 

Statement functions 

Minimize the use of TYPE statements, especially 
TYPl HEAL and TYPE INTEGER. 

3.3.2 FORMAT STATEMENTS 

Place FORMAT stateaents where they are easy to 
find. Group them all at tne end or tne program, 
except those sinple FOBMAT stateaents used oy 
only one I/O statement, which snould he placed 
with that I/O stateaent. all FORMAT statement 
numbers are to be five-digit numbers (ptereranly 
2XXXX and larger) and increase seguentiaily. 

3.3.3 STATEME NT NUMBERING 

Statement numbers are to increase sequentially 
from physical neginning to physical end of the 
executable stateaents. This peraits easy 
following of transfers. Using separate ana 
distrinct blocks of statement numbers (statement 
numbers increase by 50, 100, 500 or 1000 
depending on amount of code m the block) in 
different sections of the program to emphasize 
the structure, to have large enough gaps for 
future modifications and expansions, ana prevent 
accidental duplication. Statement runners are to 
be placed on CONTINUE stateaents only ana rignt 
justified with column 5. 

3.4 SPECIF ICATI ON STAT EMENTS. COMMON S TORAGE 

3.4.1 SPEC IFYI NG V ARIA BLE TYPE 

Use only one type specification for a vananie 
name. When you must change the type 
specifications of integer or real variances, 
rename fnern in EQUIVALENCE statements, using 
names beginning with 1 through N for integers and 
with other letters for other variables. 
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3.4.2 COMMON BLOCKS 

The structure of each block of common storage, as 
specified in COMMON and in any other related 
specification statements (e.g., DIMENSION, 
INTEGER, EQUIVALENCE) , should be the same for the 
main program and all subroutines using it. All 
COMMON should be labeled and in alphabetical 
order, unless blank COMMON is necessary for 
communication between ChAlN segments. Use 
several blocks, rather than putting unrelated 
data into the same block; this incurs no penalty 
and prevents the confusion of variables specified 
but not used in a subroutine. 

Thus the specification statements for each olocx 
of COMMON can be reproduced exactly ana a copy 
inserted into each subroutine using it. Fo i 
legibility, separate the blocks by blank C cards 
and use comments to explain the purpose of the 
blocks, where necessary. Corresponding CcaduN 
and DIMENSION statements should be ordered and 
spaced the same way. 

3.5 VARIABLE NAMES 
3.5.1 GENERAL 

Unless awkward, use variable names that are 
meaningful in the context of the problem t.jk- 
program is to solve and that correspond to — 
notation or terminology in the block diagram and 
program document. This helps make the listing 
self-explanatory and relates it to the block 
diagram and document. For example, two arrays, 
one of positive and the other of negative values, 
that are denoted in the block diagram and 
documentation as 

(♦) (+) (-) 1 -) 
x t ,x 2 ,... and Xj ,x 2 ,... 

should be given names like IPGS and XNEb, ratner 
than A and B. 
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3.5.2 CONSTANTS 

Use variable names for quantities that might be 
expressed as constants. Examples of sucn 
quantities are the number of times a loop is to 
be performed, the length of a vector, or an i/G 
device number. Set the values of these 
quantities during initilization (in a DATA 
statement if possible) ; thus they can be 
redefined, if necessary, in one place at tne 
beginning of the program. Accordingly, rerer to 
I/O files or devices by integer variables ratner 
than by constants. For example, instead or using 
the constant 3 in several output statements, use 
a variable such as TOUT that is initialized to 3. 
Then, if the files or devices are reorganized, 
the analyst can simply change the definition o t 
I OUT and need not look for all appearances of 3 
in this context. 

3.5.3 NAMI NG CONVENTION 

In naming variables, use names beginning with I 
tnrough N for integer variables, and names 
beginning with A tnrough H and 0 through Z for 
other variables. This widely accepted convention 
reduces confusion. Avoid using variable names 
similar to FORTRAN verbs. Some compilers might 
treat them as commands instead of variable names. 


3.6 ARRAYS 


3.6.1 COM BINING 

Do not needlessly combine into one array wnat 
could be separate arrays with fewer dimensions. 
Similarly do cot needlessly form a singly- 
dimensioned array from what could be sample 
variables. The time and storage required for 
index manipulation increases as the numoer or 
dimensions increases. When the only reason ior 
such combining is to make separate arrays or 
simple variables adjacent, this can be 
accomplished by an EQUIVALENCE statement teat 
equates the arrays or simple variables to the 
elements of an array into which they might nave 
been combined. 
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3.6.2 SUBSCRIPTS 

Whenever referring to an eienent of an array , 
include a subscript for each aimension. Although 

A(1,1)-0. 

can sonetines be expressed 

A=0 . 

not all conpilers will accept it, and it nay 
confuse some programmers. 

3.6. 3 U SAG E IN SUBPROGRAMS 

An array included in the calling seguence of a 
s unroutine nust appear in a DIMENSION statement 
in the subroutine. Possibly tae subroutine does 
not use the array nut passes it on to another 
subroutine. However, sone coapilers require that 
the DIMENSION statenent be included in this type 
of subroutine to ensure that tne array is passed 
by naie and not by value. Also, the dimensioning 
information makes visually apparent in the 
program listing what are arrays ana not simple 
variables. 

A useful convention for sing ly- dimensioned arrays 
is that the DIMENSION statement specify a length 
of 1 if the length of the array is variable (to 
the subroutine), and the actual length if it is 
fixed. Tnis convention also applies to tne last 
subscript of a multiply-dimensioned array (the 
other subscripts must agree exactly witn those in 
the calling program) . 

3.7 ARITHMETIC EXPRESS IONS AND STATEMENT S 

3.7.1 UNAM BI GUOUS USAG E 

Use parentheses tc make arithmetic expressions 
completely unambiguous. The expression a**b**C 
is computed from rignt to left by some compilers; 
from left to right by others. Similarly, tne 
expression I*J/K could mean I* ( J/K) or (i*o)/K, 
and the expression A/B*C could mean C*A/B or 
A/(B*C) . 
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Do not cel/ on tne order o f the evaluation within 
a single arithmetic expression. For example, 
instead of the statement X=F1 (X) +F2 (X) , where FI 
and F2 are functions to he taken in that order 
because one depends on the other, use two 
statements; i.e., I=F1 (X) followed by Y=I+F2{X). 

3.7.2 TEST FOB IHPROPEB CONDITIONS 

When undefined operations are possible, sucn as 
division by zero or taking the sguare coot of a 
negative argument, test in advance for improper 
conditions. 

3.7.3 COMPOUND EXPRESSIO NS 

Replace compound expressions repeated in 
arithmetic statementts by single variables 
previously set to the values of the expressions. 
This not only simplifies tne appearance of 
expressions and statements, but also saves time, 
storage, and helps to debug the expression. 
Although some compilers have an optimization 
feature, this is a gopd practice to get into. 

For example, in the statement: 

I * (A*B) /C + COS (A*B) /C - SIN(.5*(A*n)/C) } 

replace the expression (a*B) /C by the variaole T; 
i.e. , 


T = (A*B)/C 

1 = T ♦ COS {T- SIN (. 5*T) ) 

Similarly, simplify expressions algebraically 
before coding then. This applies to constants as 
well as variables. For example, tor the 
circumference of a circle in inches, give., the 
radius in feet, write 


C=24.0*P1*R, not C=2.0*PI*B*12.0 
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3.7.4 USAGE OF SORT 

When practical, ase the square root function 
instead of exponentiation or other sore difficult 
operations. Generally, the SQRT subprogram is 
executed faster, is more accurate, and uses less 
storage. Also it is more likely to be already in 
core than any other elementary function 
generator. For example, use 

5QRT (X) not X**0.5 

X*SQRT (X) n<~t X**1.5 

SQRT (SQRT (X) ) not X**0.25 

Further, vhere S = S1N(X), T = COS(2.0*X) , ana 
U=SINH(X), use 

SQRT (1.-S*S) not COS (S) 

SQRT (.5* (1 ,+T) ) not COS (. 5*AcG5 (1) ) 

SQRT (1.+U*U) not COSH (ASINH(Uj) 

In general, replace complicated operations by 
simpler operations when possible. For example, 
to compare the distance between the points 
(Xj, 7j) and (Xi, Yi) with a prescribea tolerance 
T, use 

IF ((XI-XJ)**2+(YI-YJ)**2-T*1) HI, HI, H 3 
rather than 

IF (SQRT ( (XI-XJ) **2+ (Yl-YJ) **2) -T) Ml, N2, N3 

Given a set of N points whose coordinates are 
stored consecutively in the singly-dimensionea 
arrays X and Y, to find the distance between tne 
origin and the point farthest from it, use 


0 = 0 . 

DO 100 1=1, N 

D = ABAX (D,X(1) **2+Y(l) **2) 
100 CONTINUE 

D = SQRT (D) 
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rather than 

D = 0. 

DO 100 I = 1,H 

D = AMAX (D,SQRT (X(l) **2+ (1) **2 ) ) 
100 CONTINUE 

The first method saves N-1 square root 
calculations. 


3.7.5 PREFERRED CONSTRUCTIONS 

To speed execution or to conserve storage, use 
the following preferred constructions (most of 
these apply to integer as well as to real 
variables) : 

To express a power of 10, use E notation, not 
exponentiation. For exaaple, the expression 
20.5E6 causes the compiler to generate a 
constant, but the expression 20.5*10.**b requires 
a calculation during execution. 

Mixed mode expressions and replacenents are 
wasteful, even when allowed by the compiler; use 

A-t-2.0 not A+2 
and A=2 . 0 not A=2 

Addition is always faster than nultiplication; use 
A+A not 2.0*A 

In a loop, multiplication oy the reciprocal is 
faster than division; use 

DO 100 1=1, N not DO 100 1-1, N 

A = 0.5*A A = A/2.0 

100 CONTINUE 100 CONTINUE 

For exponents that are whole numbers, use xixea- 
point notation. A real exponent requires tne 
general approximation algorithm of exponentiation 
whereas an integer exponent requires oniy 
repeated multiplication or a simpler 
exponentiation algorithm. For example, the 

A**2 (or A*A) not k**2.0 
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3.8 CON TROL STATEMEN TS 


3.8.1 CALC ULATIONS IN A LOOP 

Minimize the calculations performed in a loop, 
and avoid unnecessary subscripting. For example. 


DO 100 I = 1,N 
Z(I) = U*V*X(I)+Y(J) 
100 CONTINUE 


is not as efficient as 

T = U*V 
YJ = Y(J) 

DO 100 I = 1 ,N 
Z(I) = T*X (I) = YJ 
100 CONTINUE 

3.8.2 COMPUTED GO TO«S 

The control variable of a computed GO 10 
statement should be checked in advance n it is 
read from input data, received through a cabling 
sequence, or calculated from other than perrectiy 
controlled variables. All labels within computed 
GO TO statement should be sequential in ascending 
order if possible. 

3.8.3 ASSIGN STA TEMENTS 

The ASSIGN statement and tne assigned GO 10 
statement will not be used. Thus mill prohibit 
jumps both forward and bacxward in the coae. 
Transferring ail over the routine makes it 
difficult to follow the logic of the routine and 
routine complexity grows with additions ana 
changes during the checkout. 
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3. a. 4 D£ LOOPS 

Usually, the indexing parameter of a DO-ioop has 
a range of permissible positive values, ana zero 
is an unlikely hut possible value. Therefore, 
check the indexing parameters of 00-loops, and of 
implicit 00-loops in READ and WRITE statements, 
if there is any cnange of a zero value. For 
example, 

J = 0 

DO 100 1=1, N 
J = J+r 
100 CONTINUE 

N 

gives the wrong value for J = li 
when a = 0, whereas i= 1 

J = 0 

IF(N.LE.O) GO TO 200 
DO 100 I = 1, N 
J = J + 1 
100 CONTINUE 
200 ... 

work for all values of N. 

3.8.5 CALL STATEMENTS 

Avoid literal arguments in CALL statements. If a 
subroutine changes the value of an argument 
passed as a literal constant, suhseguent use of 
that constant by the calling program xs invalid. 
For example, if the following occurred, 

CALLING PROGRAM SUBROUTINE SUb (d) 

• • 

• • 


CALLING SUB (3) 
1=3 



RETURN 


every subsequent use of the literal constant 3 in 
the calling program will actually use a value of 
2. In tne example 2, not 3, will be stored m i. 
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3.9 WUT/QOIPO I 

3.9.1 BECO BD FORMAT 

When a widely used record format is appropriate 
or nearly so, do not in rent a new one. 

Minimize the number of formats tor input data. 
Generally, the fewer forms in which data must be 
prepared, the less susceptible it is to error and 
the less storage the program requires. 

For example, many programs could use a singie 
input format, such as 7E10.0. Data couxd oe 
converted to fixed-point, if necessary, axter it 
is read. This would make keypunching easier ana 
errors less likely because all numeric input 
could be punched with decimal points ana, more 
importantly, could be left justified in the 
fields. Even when standaraizing the input 
increases the number of cards, the benefits or 
convenience and fever errors outweigh the cost of 
additional cards and of processing them. 

Avoid writing short records on tape. For a given 
amount of data, the fewer the number or records, 
the less likely are read/write errors, the 
greater is the read/write speed, and tne smaller 
is tne amount of tape used. Also, short records 
can cause tape positioning problems. Avoid tape 
records of fewer tnan about 80 characters; they 
are likely to cause read errors. 

If only a few characters are to ne written, 
repeat them enough times (or insert dummy 
characters) to form a record of at least 80 
characters. Rhen the recora is subsequently 
read, the READ statement would, of course, be tne 
same as if the redundant or aummy characters were 
not there. 
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For example, instead of 

WRITE <J,1) A,B,C,D 

• • • 

• • • 

• • • 

READ (J,1) A,B,C,D 

• • • 

• • «i 

• • • 

use 

WRITE (J,1) A,B,C, (b,I=1 , 11) 

• • • 

• • • 

• • • 

READ (J,1) A,B,C,D 

When writing aultiple-f ile tapes, it is a good 
practice to have an End-of-File (E?F) mark after 
each file, and two after tne last file on the 
tape. Thus, a programmer does not need to Know 
how many files there are on the tape in order to 
process the whole tape. Also, using tnis 
convention, it is quite simple to position tne 
tape to the desired file by skipping files. 

3.9.2 PLAC E& ENI OF 1/0 OPERATIONS 

isolate input and output operations, except 
perhaps for the permanent input and output files, 
in subroutines. This allows easier relocation of 
scratch files from tape to disk, or modification 
of a plotting tape for new plotting hardware, 
software, or performance requirements. 

3.9.3 DEFAULT VA LUES 

On card or terminal input, it is a gooa practice 
to have default values witnin the program for 
some input variables. Thus, by leaving the field 
blank, the program automatically presets tne 
variable to some commonly-used value. 
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inis is a good convenience lor the user, for 
e ran pie, blank start-stop tines on an input card 
could aean to process all data by having tne 
prograa set the tines to the smallest and largest 
possible values; a blank aultiplicative tine bias 
would cause the program to set the bias to 1. 

Care must be exercised/ however/ when reading 
blank fields which will read in as negative zero 
on nuneric variables. Since zero is a possible 
data value, a further check lor negative zero nay 
have to be made. 

All input data read in on control cards snoula be 
printed out/ just as it was read in but clearly 
laneled. This allows for guicx identification or 
keypunch errors should the progran erroi orf or 
give the wrong results. 

3.9.4 OUTPUT FORM 

Output froa production prograas snoula ne 
oriented to the user. Clearly identify output as 
to tne naae of the calculation/ the name and 
nuaber of the prograa producing it, and the date. 
Laoel printed output and, it the printout is 
expected to end up on document paper, limit its 
length and width to the dimensions of the 
document. This eliminates the need for photo- 
reduction. For example, a printout confined to a 
rectangle about 7-1/2 inches wide by 10 inches 
long could be trimmed and bound as 8-1/2 by 11 
incn material. Number and date the pages of a 
printout when the application calls ror it. ior 
the date, use an existing general-purpose 
subroutine. 

3.9.5 E RRO R ME SSA GES 

Provide for laneled printout when errors oocur to 
explain the reasons for the errors. Hake tne 
explanation meaningful to tne user as well as to 
the programmer. This frees the user or the 
necessity of looking up the meanings or erroi 
codes in separate documents. Tnese printouts 
also should explain what counters, etc., are 
crucial for locating the source of tna errors. 
General-purpose subroutines should net, of 
course, write such messages. All error messages 
produced by the program should be clearly 
identified as such (e.g. "*** PhOG XYZ EERoE") 
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3.9.6 INTERMEDIA TE OUTPUT 

Make available to . the user an option for 
ontaining selected inter* aiate output. An input 
rde can easily be used to indicate which 
interned *te results, if any, are desired. 

3.9.7 CAfcD R EADI NG 

Explicitly control the reaamg of large numbers 
of cards. A control integer specifying the 
number of cards in a set can easily be wrong aue 
to niscounting. if the integer is too big, the 
program nay read to the ena of the data ana be 
terminated; if it is too small, the next input 
statement will read the wrong cards. One 
alternative is to punch a flag in the last cara 
so the program can recognize it. For example 


N=0 

100 CONTINUE 
N=N + 1 

BEAD (5, 110) (X (N,l) , 1*1,7) ,K 
110 FORMAT (7E10 .0,12) 

IF (K.EQ.0) 60 TO 100 

is preferable to 

B£AD(5,110)N,((X(J,I) ,1=1,7) ,J=1,N) 

110 FORMAT (I10/(7E10.0) ) 

and obviates manual card counting and the 
associated error possibility. 

Anotner alternative, when a particular field is 
non-zero on all cards in tne set, is to insert a 
blank card behind the last card of the set and 
reaa it as follows: 


N=0 

100 CONTINUE 
N*N + 1 

READ (5,110) (X (N,I) , 1=1,7) 

110 FORMAT (7E10.0) 

IF (X (N, 1) . ME. 0) GO TO 100 
N=N- 1 

This way, a card need not be punched witn a flag 
that might later have to be removed when tne set 
is enlarged. 
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3.10 

The tern "subroutine M as used here means either 
SUBROUTINE or FUNCTION SUBPROGRAM. 

3.10.1 GBN gfijjf 

Code a group of logically related Instructions as 
a subroutine, rather than as in-line coding if 
it: 


- Is entered from several different places in the 
program. 

- is potentially of general-purpose value. 

- Is less stable than other parts of tne program; 
or 

- Is simply of appropriate size to be a separate 
module. 

Subroutines concretely express the concept of 

modular programming* 

3.10.2 CALLING ARGUMENT S 

For ease of interpretation, group the arguments 

of a calling sequence in this order: input, 

input/output, output, error code. 

- An input argument is one whose value tne 
subroutine uses nut does not change. 

- An input-output argument is one whose vaiue the 
subroutine uses and subsequently changes. 

- An output argument is one whose value tne 
subroutine does not use but does change. 

- The error code argument is the aeans of 
transmitting diagnostic information to tne 
calling program, such as whether the subroutine 
executed normally or abnormally; it is a special 
case of ar. output argument. 
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3.10.3 EBBOR CODES 

in error code returned by a subroutine should be 
zero for nor sal execution and a non-zero value 
otnerwise. The more specifically it can describe 
to the calling program the nature of a 
malfunction or improper condition in the input 
data. 

A general-purpose subroutine should not write 
diagnostic messages or cause other input/output 
operations unless that is its principal function. 
Error codes should be returned through tne 
calling sequence. The user of the subroutine 
then is not restricted as to tne words in, 
position of, and storage for diagnostic messages. 
Further, he has a change to recover gracefully. 

3. 1 0. RETURN ST ATEMEN TS 

Use only one simple RETURN statement in a 
general-purpose subroutine, and place it 
physically as the last executable statement. 
Connect other places where the logic fiow 
terainates to the RETURN statement by aQ 10 
statements. This eases later insertion of 
statements that must be executed before any 
return is made. Note that this method stixi 
leaves the various paths to termination distinct 
so that they can be treated separately wnen 
necessary. 

3.10.5 ARRA.fS 

If a subroutine uses a variable-length or large 
fixed-length array for working storage, transmit 
it to the subroutine through the calling 
seguence. This way, the array is in tne data 
region of the calling program and can satisfy 
otner needs for temporary storage. Also, ir the 
array varies in length from case to case in a 
single program, or from program to program, and 
is not specified in the calling sequence, tne 
array as defined in the subroutine couia be 
either short and sometimes insufficient or long 
ana sometimes wasteful. 

L. ait the output of a subroutine to prevent array 
overflow in the calling program, hhen an output 
array from a subroutine is of variable length, 
the maximum allowanle length must be communicated 
to the subroutine by an argument in the calling 
seg uence. 
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3.10.6 COflMO h BLOCKS 

Use labeled COMMON for passing arguments to or 
from special-purpose subroutines whenever 
possible. 

a subroutine must not change the value of an 
input argument. 

General-purpose subroutines should not use b^ank 
COMMON storage. One that does limits the calling 
program in its use of COMMON. Two or more that 
do are likely to nave incompatible requirements 
the sizes or names of blocks in COMMON, which 
necessitate awkward modifications when the 
subroutines are used together. 
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CdECKOUT AIDS 
4.1 INTERMEDIATE RESULTS 
4.1.1 PROG RAH FLOW 

Place WRITE statements In all major blocks oi tie 
program and its subroutines when first coded, so 
tnat the progress of a program can be traced from 
its printed output during debugging. Do not rely 
on the ordinary (production) output, at least 
have each special-purpose sunroutine print its 
name as soon as it is entered. It is also useful 
to ~rint the input variables to a subroutine just 
before and the output variables just after the 
CALL statement. These statements shouxa print a 
clear indication of their position in tne 
program, and any variables printed should re 
laneled . 

In tracing the flow of a program, integer control 
variables are generaiiy more helpful that are 
floating-point data, although tne floating-point 
values may be needed to check the numerical 
algorithm. So it is better initially to code 
many simple WHITE'S of integer vairables, sucn as 
indices and counters, matrix dimensions, flags 
and switches, error codes and computed GO To 
variables, than a few aassrve WHITE'S of 
floating-point arrays. 

The WRITE statements used in debugging, and their 
associated FORHAT statements, may re identified 
by a word such as TRACE or DEBUG in columns 
73-80, so that they are easily removed after 
checkout. Alternatively, a C can simply be added 
in column 1 so that the statements can re used 
again if the program is modified. 
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4.1.2 DA1A SIB PCTOBBS 

Design data structures sensibly so they can be 
displayed either in dumps or in labeled ana veil 
arranged printout. Such printing requires extra 
coding initially, nut this extra code can ne 
included in an error handling subroutine that 
provides easily read diagnostic information vnen 
and only when needed. It also provides a 
convenient checkout device in program 
aodif ication, tor a CALL to this subroutine can 
be inserted both before and after tne nodnied 
prog rax section. This lessens the need to invent 
intermediate output statements or dump 
procedures, vhich usually faij. to include all the 
portions of storage required to diagnose tne 
error. 

4.1.3 VALIDITY OF BESPITS 

For programs expected to run a long tine, provide 
for freguent c necks of the validity of results. 
Hhen the results seen invalid, and the error is 
irrecoverable, execution saouid be terainatea. 


4.2 DESK 


4.2.1 GENERAL 


Desk checking means manually scrutinizing program 
logic and deck structure. Mistakes in eitaer can 
cause an unsuccessful run, so a rev Minutes of 
c necking is vorthvhiie. 
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4.2.2 PROGRAM LOGIC CHECK j4ST 

* is there a statement nuhoer on the statement 
immediately following each arithmetic if 
statement and each of alx kinds of GO 1C 
statements? 

- Are there statement numbers for the exist from 
if, GO TO, and DO state ments? 

- Do. parentheser balance? start from tne left 
with 0 and adu 1 for each left parenthesis 
encountered and subtract 1 tor each rignt 
parenthesis. The count shouia never oecome 
negative. If parentheses balance, tne count 
will end up at 0; however, this does not 
necessarily indicate correct grouping. 

- Does every sunscriptea variable appear m a 
specification statement? 

- Does any DO- loop end witn an IP statement, c 
GO TO statement? 

- Are ail referenced FORMAT statements present? 

- is the field length correct for all Hollerith 
fields? 

- Are the number, order, and type or arguments 
in CALL statements correct? 

4.2.3 DECK STRUCTURE CHECK LIST 

- For Control cards: is tne card necessary, is 

its position in the deck consistent witn its 
purpose, and is its format correct? Are any 
control cards missing? 

- Are ail necessary subroutine decks present? 

- Are all necessary data cards present, and coes 
their order agree kith what tne prograa expects 

- is the deck properly identixied witn your name 
phone number, location, etc.? 
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4.3 CHECKOUT DATA 

4.3.1 GEMERAL 

When creating checkout data, remember that 
anything that can be punched on a card, written 
in a tape record, etc., will possibly ne input to 
your program sooner or later. A program is never 
100 percent checked out, but you are responsible 
for making checkout as complete as possinie. 
Therefore, prepare checkout data that represent 
production conditions, including both valid and 
invalid data, to test diagnostxcs and recovery 
features. 

Keep test decks ana records of test results up- 
to-date. When nev features are added to a 
prograa insert representative checkout aata. 
Whenever a prograa fails and is corrected, 
include in the test' deck the type of data that 
caused the failure. 

When a prograa is revised or recompiled, check it 
with the old test deck as veil as the new 
checkout data, if the old deck is stilx 
applicable. 

4.3.2 VERIFI CATI ON OF INPUT 

Knov your input. When practical, have checkout 
data printed out completely xn a readable roraat 
before using it, so you can check it. (To xist 
out input cards, use an existing general-purpose 
suoroutine.) When the input to a prograa, 
particularly a general- purpose routine, consists 
of a large amount of data, another routine to 
check the data for consistency, rather tnan 
printing it all out, could be helpful. Another 
technique for handling a large amount of data is 
to write it in a scratch fixe and use an existing 
general-urpose subroutine to transfer it to tne 
output file after execution. 
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4.4 D UMPS 

4.4.1 GEMEBAL 

If trace printouts are systematically used, tnere 
should be only infrequent need for core dunps. 
Since the latter are more expensive in computer 
time and less useful as a debugging aia than 
selective labeled printout, the only dunp that 
should always be provided for is a conditional 
post-mortem of crucial regions of storage, such 
as the data region of the main program, in case 
of abnormal job termination. But, do not rely on 
a post-mortem dump as a substitute for trace 
printouts; they will tell only what the program 
looked like after the crash, not necessarily way 
it crashed. 

4.4.2 COP E DUMPS 

Generally core dumps are userul only to more 
experienced programmers, most of whom will 
maintain that they cannot work efficiently 
without them. However, new programmers will not 
have a good understanding of the computer's 
workings until they are at least capable of 
understanding dunps. 

4.4.3 TECHNIQUE 

Tne technique of using dumps is best le£t to tne 
judgment of the individual programmer, hut tne re 
are a few general principles: 

- When a dump is positioned in a loop, he sure to 
include the relevant control variables, such 

as the indexing parameter of the loop. 

- When preparing a production run, always 
provide for a full core dump in the event 

of failure detected by tne operating system; 
this aids immensely in investigating operating 
system and/or hardware malfunctions. A fun 
core dump in the event of failure detected oy 
the program may or may not be appropriate. 

- Carefully select the regions to be included in 
a dump; but, when in doubt, include too much 
rather than too little. 


ORIGINAL page is 
OF POOR QUALITY 


4.4.4 INSTRUCTION DOflPS 

Another occasional need for a duap is to examine 
instruction regions suspected of having been 
improperly generated by the compiler or of naving 
been lutilated during execution. Since the 
instruction region cannot be written out by NRiiE 
statements, a duap with aneaonics can be a great 
help, to those who can interpret it, in isolating 
these errors. 

4.5 STORAGE MAP S 
4.5.1 GENERAL 

Get a storage aap, which snows how the prograa 
uses aain storage, and use it in checkout. Be 
sure to watch for: 

* Variable naaes that do not belong tnere, nut 
appear because of misspelling or other 
mistakes. 

- Arrays treated as functions because they are 
not specified in DIMENSION statements. 

- Proper size of COMMON storage for all routines 
using it. 

Get a loading aap, which snows how all of core is 
allocated to aake for easier interpretation of 
duaps. 

4.6 DIAGN OSTICS 

When you discover an error in checking out a prograa, ao 
not resubmit the prograa until you have checked tne 
diagnostic information of other errors. Often several 
prograa errors can be detected from the diagnostics or 
one checkout run. Examine partial results and incorrect 
results; even these can be helpful. For example, try to 
ascertain why deviations froa expected or pre-calculatea 
results occurred. 

4.7 P ROGRA M TIMING 

To time a section of a prograa, use an existing general** 
purpose timing subroutine when the section is entered 
and when it exits. 


